General: Forums subtopic: App & System Services > Networking DevForums tag: Network Extension Network Extension framework documentation Routing your VPN network traffic article Filtering traffic by URL sample code Filtering Network Traffic sample code TN3120 Expected use cases for Network Extension packet tunnel providers technote TN3134 Network Extension provider deployment technote TN3165 Packet Filter is not API technote Network Extension and VPN Glossary forums post Debugging a Network Extension Provider forums post Exporting a Developer ID Network Extension forums post Network Extension Framework Entitlements forums post Network Extension vs ad hoc techniques on macOS forums post Network Extension Provider Packaging forums post NWEndpoint History and Advice forums post Extra-ordinary Networking forums post Wi-Fi management: Wi-Fi Fundamentals forums post TN3111 iOS Wi-Fi API overview technote How to modernize your captive network developer news post iOS Network Signal Strength forums post See also Networking Resources. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com"

I haven’t been able to get this to work at any level! I’m running into multiple issues, any light shed on any of these would be nice: I can’t implement a bloom filter that produces the same output as can be found in the SimpleURLFilter sample project, after following the textual description of it that’s available in the documentation. No clue what my implementation is doing wrong, and because of the nature of hashing, there is no way to know. Specifically: The web is full of implementations of FNV-1a and MurmurHash3, and they all produce different hashes for the same input. Can we get the proper hashes for some sample strings, so we know which is the “correct” one? Similarly, different implementations use different encodings for the strings to hash. Which should we use here? The formulas for numberOfBits and numberOfHashes give Doubles and assign them to Ints. It seems we should do this conversing by rounding them, is this correct? Can we get a sample correct value for the combined hash, so we can verify our implementations against it? Or ignoring all of the above, can we have the actual code instead of a textual description of it? 😓 I managed to get Settings to register my first attempt at this extension in beta 1. Now, in beta 2, any other project (including the sample code) will redirect to Settings, show the Allow/Deny message box, I tap Allow, and then nothing happens. This must be a bug, right? Whenever I try to enable the only extension that Settings accepted (by setting its isEnabled to true), its status goes to .stopped and the error is, of course, .unknown. How do I debug this? While the extension is .stopped, ALL URL LOADS are blocked on the device. Is this to be expected? (shouldFailClosed is set to false) Is there any way to manually reload the bloom filter? My app ships blocklist updates with background push, so it would be wasteful to fetch the filter at a fixed interval. If so, can we opt out of the periodic fetch altogether? I initially believed the API to be near useless because I didn’t know of its “fuzzy matching” capabilities, which I’ve discovered by accident in a forum post. It’d be nice if those were documented somewhere! Thanks!!

I added a Content Filter to my app, and when running it in Xcode (Debug/Release), I get the expected permission prompt: "Would like to filter network content (Allow / Don't Allow)". However, when I install the app via TestFlight, this prompt doesn’t appear at all, and the feature doesn’t work. Is there a special configuration required for TestFlight? Has anyone encountered this issue before? Thanks!

We create custom VPN tunnel by overriding PacketTunnelProvider on MacOS. Normal VPN connection works seamlessly. But if we enable onDemand rules on VPN manager, intemittently during tunnel creation via OnDemand, internet goes away on machine leading to a connection stuck state. Why does internet goes away during tunnel creation?

We've often observed connectivity issues from our VPN app that can only be remedied by removing the VPN profile. It happens to a small but significant amount of our users, this often happens more when the app is updated, but the VPN profile corruption can happen without that too. The behavior we're observing is that any socket opened by the packet tunnel process just fails to send any data whatsoever. Stopping and restarting the packet tunnel does not help. The only solution is to remove the profile and create a new one. We believe our app is not the only one suffering from this issue as other VPN apps have added a specific button to refresh their VPN profile, which seemingly deletes and re-created the VPN configuration profile. Previously, we've caught glimpses of this in a sysdiagnose, but that was a while ago and we found nothing of interest. Alas, the sysdiagnose was not captured on a device with the network extension diagnostic profile (it was not a developer device). I would love to get technical support with this, as our bug reports have gone unanswered for long enough, yet we are still struggling with this issue. But of course, there is no minimum viable xcodeproject that reproduces this. Is there anything we can feasibly do to help with this issue? Is it even an acknowledged issue?

I added a Content Filter to my app, and when running it in Xcode (Debug/Release), I get the expected permission prompt: "Would like to filter network content (Allow / Don't Allow)". However, when I install the app via TestFlight, this prompt doesn’t appear at all, and the feature doesn’t work. Is there a special configuration required for TestFlight? I already set the minimum deployment to be 17 for the extension and the app. Thanks!

We have an application which is written in Swift, which activates Transparent Proxy network extension. Our Transparent Proxy module is a system extension, which is exposing an app proxy provider interface (We are using NETransparentProxyProvider class and in extension’s Info.plist we use com.apple.networkextension.app-proxy key.) Sometimes we have observed that on starting the transparent proxy extension, the startProxy overridden delegate method(override func startProxy(options: [String : Any]?, completionHandler: @escaping (Error?) -> Void) {) in our AppProxyProvider class which is derived from NETransparentProxyProvider being called more than once for the same extension(pid). This leads to Over-resume of an object crash as we invoke setTunnelNetworkSettings inside the startProxy delegate. As this is controlled by the system, we are not sure why this delegate being called more than once sometimes even if we call the start TransparentProxy only once. Note that, this issue is seen only in Mac OS Tahoe. Apple Feedback ticket: FB21464147 (startProxy delegate for NETransparentProxyProvider class is being called twice for the same pid extension sometimes)

I filed FB19631435 about this just now. Basically: starting with 15.6, we've had reports (internally and outternally) that after some period of time, networking fails so badly that it can't even acquire a DHCP lease, and the system needs to be rebooted to fix this. The systems in question all have at least 2 VPN applications installed; ours is a transparent proxy provider, and the affected system also had Crowdstrike's Falcon installed. A customer system reported seemingly identical failures on their systems; they don't have Crowdstrike, but they do have Cyberhaven's. Has anyone else seen somethng like this? Since it seems to involve three different networking extensions, I'm assuming it's due to an interaction between them, not a bug in any individual one. But what do I know? 😄

Hello, I have a .app that runs as LaunchDaemon and configured to be an Agent (LSUIElement) that is stored in /Applications. Installing network extensions works, but deactivation fails with OSSystemExtensionErrorDomain error 13 (authorization required). requestNeedsUserApproval is not called for deactivation, but it's called when being activated. Any ideas? Thank you! P.S. It works on Debug, just not on Release...

Hi all, I have a working macOS (Intel) system extension app that currently uses only a Content Filter (NEFilterDataProvider). I need to capture/log HTTP and HTTPS traffic in plain text, and I understand NETransparentProxyProvider is the right extension type for that. For HTTPS I will need TLS inspection / a MITM proxy — I’m new to that and unsure how complex it will be. For DNS data (in plain text), can I use the same extension, or do I need a separate extension type such as NEPacketTunnelProvider, NEFilterPacketProvider, or NEDNSProxyProvider? Current architecture: Two Xcode targets: MainApp and a SystemExtension target. The SystemExtension target contains multiple network extension types. MainApp ↔ SystemExtension communicate via a bidirectional NSXPC connection. I can already enable two extensions (Content Filter and TransparentProxy). With the NETransparentProxy, I still need to implement HTTPS capture. Questions I’d appreciate help with: Can NETransparentProxy capture the DNS fields I need (dns_hostname, dns_query_type, dns_response_code, dns_answer_number, etc.), or do I need an additional extension type to capture DNS in plain text? If a separate extension is required, is it possible or problematic to include that extension type (Packet Tunnel / DNS Proxy / etc.) in the same SystemExtension Xcode target as the TransparentProxy? Any recommended resources or guidance on TLS inspection / MITM proxy setup for capturing HTTPS logs? There are multiple DNS transport types — am I correct that capturing DNS over UDP (port 53) is not necessarily sufficient? Which DNS types should I plan to handle? I’ve read that TransparentProxy and other extension types (e.g., Packet Tunnel) cannot coexist in the same Xcode target. Is that true? Best approach for delivering logs from multiple extensions to the main app (is it feasible)? Or what’s the best way to capture logs so an external/independent process (or C/C++ daemon) can consume them? Required data to capture (not limited to): All HTTP/HTTPS (request, body, URL, response, etc.) DNS fields: dns_hostname, dns_query_type, dns_response_code, dns_answer_number, and other DNS data — all in plain text. I’ve read various resources but remain unclear which extension(s) to use and whether multiple extension types can be combined in one Xcode target. Please ask if you need more details. Thank you.

Hi everyone, I’m exploring Network Extension options for a use case where I need to log and filter network activity at the packet level. More specifically, I need the ability to detect and potentially block certain TCP behaviors during the handshake. From everything I’ve tested, NEFilterPacketProvider seems to be the only Network Extension type that operates early enough in the flow. NEFilterDataProvider appears to receive flows after the TCP handshake is already completed. It also has some limitations with IP-based filtering (might include hostname instead of IP), inconsistent ICMP behavior, etc. So I went with NEFilterPacketProvider. However, I’m running into a major issue: extremely high CPU usage. To isolate the problem, I stripped my packet handler down to the simplest possible implementation — basically returning .allow for every inbound/outbound packet without any filtering logic. Even with that minimal setup, playing one or two videos in a browser causes the CPU usage of the extension to spike to 20–50%. This seems to be caused purely by the packet volume. I haven’t found any way to pre-filter packets before the handler is invoked, nor any documented method to significantly optimize packet handling at this stage. It’s possible I’m missing something fundamental. Questions: Has anyone else experienced this kind of high CPU usage with NEFilterPacketProvider? Is there any recommended way to reduce the packet handling overhead or avoid processing every single packet? Any known best practices or configuration tips? Thanks in advance!

Hi there, We have been trying to set up URL filtering for our app but have run into a wall with generating the bloom filter. Firstly, some context about our set up: OHTTP handlers Uses pre-warmed lambdas to expose the gateway and the configs endpoints using the javascript libary referenced here - https://developers.cloudflare.com/privacy-gateway/get-started/#resources Status = untested We have not yet got access to Apples relay servers PIR service We run the PIR service through AWS ECS behind an ALB The container clones the following repo https://github.com/apple/swift-homomorphic-encryption, outside of config changes, we do not have any custom functionality Status = working From the logs, everything seems to be working here because it is responding to queries when they are sent, and never blocking anything it shouldn’t Bloom filter generation We generate a bloom filter from the following url list: https://example.com http://example.com example.com Then we put the result into the url filtering example application from here - https://developer.apple.com/documentation/networkextension/filtering-traffic-by-url The info generated from the above URLs is: { "bits": 44, "hashes": 11, "seed": 2538058380, "content": "m+yLyZ4O" } Status = broken We think this is broken because we are getting requests to our PIR server for every single website we visit We would have expected to only receive requests to the PIR server when going to example.com because it’s in our block list It’s possible that behind the scenes Apple runs sporadically makes requests regardless of the bloom filter result, but that isn’t what we’d expect We are generating our bloom filter in the following way: We double hash the URL using fnv1a for the first, and murmurhash3 for the second hashTwice(value: any, seed?: any): any { return { first: Number(fnv1a(value, { size: 32 })), second: murmurhash3(value, seed), }; } We calculate the index positions from the following function/formula , as seen in https://github.com/ameshkov/swift-bloom/blob/master/Sources/BloomFilter/BloomFilter.swift#L96 doubleHashing(n: number, hashA: number, hashB: number, size: number): number { return Math.abs((hashA + n * hashB) % size); } Questions: What hashing algorithms are used and can you link an implementation that you know is compatible with Apple’s? How are the index positions calculated from the iteration number, the size, and the hash results? There was mention of a tool for generating a bloom filter that could be used for Apple’s URL filtering implementation, when can we expect the release of this tool?

When using the NEHotspotConfigurationManager applyConfiguration interface for network connection.Sometimes there is a pop-up prompt when the connection fails, and sometimes there is no pop-up prompt. Why is there no pop-up prompt when the connection fails

Hello eveybody,Currently I'm working on an app which connects to a device. During testing I encounter an internal error of NEHotspotConfigurationErrorDomain. See the log snippet:Domain=NEHotspotConfigurationErrorDomain Code=8 "internal error." UserInfo={NSLocalizedDescription=internal error.}This error appears randomly. In one day I encountered it three times. The only solution I can think of is catching this error somehow and then telling the user to restart the device.After this error appears, the wifi functionality of iOS in all third party apps seems to be broken. Only restarting helps as far as I know. Also there seems to be nothing we as app developers can do about it. Therefor I wonder if there is some way to prevent this error somehow? The only solution I can think of is catching this error somehow and then telling the user to restart the device.Also since there is not much information about this error on the web, it would be really nice if someone can clarify whats going on with this error.Regards.

This is just an FYI in case someone else runs into this problem. This afternoon (12 Dec 2025), I updated to macOS 26.2 and lost my network. The System Settings' Wi-Fi light was green and said it was connected, but traceroute showed "No route to host". I turned Wi-Fi on & off. I rebooted the Mac. I rebooted the eero network. I switched to tethering to my iPhone. I switched to physical ethernet cable. Nothing worked. Then I remembered I had a beta of an app with a network system extension that was distributed through TestFlight. I deleted the app, and networking came right back. I had this same problem ~2 years ago. Same story: app with network system extension + TestFlight + macOS update = lost network. (My TestFlight build might have expired, but I'm not certain) I don't know if anyone else has had this problem, but I thought I'd share this in case it helps.

We've received logs and have spuriously reproduced the following behavior: calls to setTunnelNetworkSettings completing with NETunnelProviderError where the code is networkSettingsInvalid, and the error domain string is empty. After subsequent calls to setTunnelNetworkSettings, the tunnel is stopped via the userInitiated stop reason within around 1 second from the first failure. This happens after a number of successful calls to setTunnelNetworkSettings have been made in the lifetime of a given packet tunnel process. We can confirm that no user ever initiates the disconnection. We can confirm that the only significant changes between the different calls to setTunnelNetworkSettings are that the parameters contain different private IPs for the tunnel settings - the routes and DNS settings remain the same. In our limited testing, it seems that we can replicate the behavior we're observing by removing the VPN profile while the tunnel is up. However, we are certain the same behavior happens under other circumstances without any user interaction. Is this what memory starvation looks like? Or is this something else? Our main concern is that the tunnel is killed and it is not brought back up even though our profile is set to be on-demand. It's difficult to give any promises about leaks to our users if the tunnel can be killed at any point and not be brought back. The spurious disconnections are a security issue for our app, we'd like to know if there's anything we can do differently so that this does not happen. We tried to get DTS, but given that we have no way to reproduce this issue with a minimal project. But we can reproduce the behavior (kill the tunnel by removing it's profile) from a minimal Xcode project, is that considered good enough for a reproduction?

Hello, I am developing an internal phone application using CallKit. I am experiencing an issue with the behavior of remoteHandle settings in iOS 26 and would appreciate any insights you can provide towards a solution. 1. Problem Description When an iPhone running iOS 26 is in a sleep state and receives a VoIP incoming call where remoteHandle is set to nil or an empty string (@""), we are unable to transition to our application (the UIExtension provided by the provider) from the CallKit UI's "More" (…) button after answering the call. 2. Conditions and Symptoms OS Version: iOS 26 Initial State: iPhone is in a sleep state Call Type: An unsolicited(unknown number) VoIP incoming call where the CXCallUpdate's remoteHandle is set to either nil or [[CXHandle alloc] initWithType:CXHandleTypePhoneNumber value:@""] Symptoms: After answering the VoIP call by sliding the button, selecting the "More" (…) button displayed on the CallKit screen does not launch our application's UIExtension (custom UI), and the iPhone instead stay to the CallKit screen. 3. Previous Behavior (Up to iOS 18) Up to iOS 18, even when remoteHandle was set to an empty string using the following code, the application would transition normally from "More" after answering an incoming call from a sleep state. CXCallUpdate *update = [[CXCallUpdate alloc] init]; update.remoteHandle = [[CXHandle alloc] initWithType:CXHandleTypePhoneNumber value:@""]; [provider reportNewIncomingCallWithUUID:uuid update:update completion:completion]; 4. Unsuccessful Attempts to Resolve The issue remained unresolved after changing the handling for unsolicited(unknown number) incoming calls as follows: CXCallUpdate *update = [[CXCallUpdate alloc] init]; update.remoteHandle = nil; // Set remoteHandle to nil [provider reportNewIncomingCallWithUUID:uuid update:update completion:completion]; 5. Workaround (Temporary) The problem can be resolved, and the application can transition successfully, by setting a dummy numerical value (e.g., "0") for the value in remoteHandle using the following code: CXCallUpdate *update = [[CXCallUpdate alloc] init]; update.remoteHandle = [[CXHandle alloc] initWithType:CXHandleTypePhoneNumber value:@"0"]; // Set a dummy numerical value [provider reportNewIncomingCallWithUUID:uuid update:update completion:completion]; 6. Additional Information If remoteHandle is correctly set with the caller's number (i.e., not an unsolicited(unknown number) call; e.g., value:@"1234567890"), the application transitions normally from the "More" button after answering an incoming call from a sleep state, even in iOS 26. The above issue does not occur when answering incoming calls while the iPhone is in an active state (not sleeping). 7. Questions Have there been any other reports of similar behavior? Should this be considered a bug in CallKit for iOS 26? Should I make file a new Feedback report? Is there a suitable method to resolve this issue when the caller ID is unsolicited (nil or an empty string)? This problem significantly impacts user operations as end-users are unable to perform essential in-app actions such as hold or transfer after answering an unsolicited(unknown number) call from a sleep state. We are eager to find an urgent solution and would appreciate any information or advice you can provide. Thank you for your assistance.

When installing a new version the app while a tunnel is connected, seemingly the old packet tunnel process gets stopped but the new one does not come back up. Reportedly, a path monitor is reporting that the device has no connectivity. Is this the expected behavior? When installing an update from TestFlight or the App store, the packet tunnel instance from the old tunnel is stopped, but, due to the profile being on-demand and incldueAllNetworks, the path monitoring believes the device has no connectivity - so the new app is never downloaded. Is this the expected behavior? During development, the old packet tunnel gets stopped, the new app is installed, but the new packet tunnel is never started. To start it, the user has to toggle the VPN twice from the Settings app. The tunnel could be started from the VPN app too, if we chose to not take the path monitor into account, but then the user still needs to attempt to start the tunnel twice - it only works on the second try. As far as we can tell, the first time around, the packet tunnel never gets started, the app receives an update about NEVPNStatus being set to disconnecting yet NEVPNConnection does not throw. The behavior I was naively expecting was that the packet tunnel process would be stopped only when the new app is fully downloaded and when the update is installed, Are we doing something horribly wrong here?

NEAppProxyUDPFlow contains below property: open var localEndpoint: NWEndpoint? { get } Why is localEndpoint not available for NEAppProxyTCPFlow? Is there a way to determine the source port of a flow of type NEAppProxyTCPFlow within the following method of NETransparentProxyProvider? override func handleNewFlow(_ flow: NEAppProxyFlow) -> Bool {

we use the api as NEHotspotConfigurationManager.shared.apply(hotspotConfig) to join a wifi, but we find that in in iphone 17+, some user report the time to join wifi is very slow the full code as let hotspotConfig = NEHotspotConfiguration(ssid: sSSID, passphrase: sPassword, isWEP: false) hotspotConfig.joinOnce = bJoinOnce if #available(iOS 13.0, *) { hotspotConfig.hidden = true } NEHotspotConfigurationManager.shared.apply(hotspotConfig) { [weak self] (error) in guard let self else { return } if let error = error { log.i("connectSSID Error while configuring WiFi: \(error.localizedDescription)") if error.localizedDescription.contains("already associated") { log.i("connectSSID Already connected to this WiFi.") result(["status": 0]) } else { result(["status": 0]) } } else { log.i("connectSSID Successfully connected to WiFi network \(sSSID)") result(["status": 1]) } } Normally it might only take 5-10 seconds, but on the iPhone 17+ it might take 20-30 seconds.